diff --git a/swh/web/ui/apidoc.py b/swh/web/ui/apidoc.py
index 895999ad2..2c15838d5 100644
--- a/swh/web/ui/apidoc.py
+++ b/swh/web/ui/apidoc.py
@@ -1,49 +1,276 @@
# Copyright (C) 2015 The Software Heritage developers
# See the AUTHORS file at the top-level directory of this distribution
# License: GNU Affero General Public License version 3, or any later version
# See top-level LICENSE file for more information
+import re
+import yaml
+import json
+
+from functools import wraps
+
+from flask import request, render_template, url_for
-import os
-from swh.web.ui import utils, main
from swh.web.ui.main import app
-def _create_url_doc_endpoints(rules):
- def split_path(path, acc):
- rpath = os.path.dirname(path)
- if rpath == '/':
- yield from acc
+class argtypes(object):
+ """Class for centralizing argument type descriptions
+
+ """
+
+ ts = 'timestamp'
+ int = 'integer'
+ path = 'path'
+ sha1 = 'sha1'
+ uuid = 'uuid'
+ sha1_git = 'sha1_git'
+ octet_stream = 'octet stream'
+ algo_and_hash = 'algo_hash:hash'
+
+
+class rettypes(object):
+ """Class for centralizing return type descriptions
+
+ """
+ list = 'list'
+ dict = 'dict'
+
+
+class excs(object):
+ """Class for centralizing exception type descriptions
+
+ """
+
+ badinput = 'BadInputExc'
+ notfound = 'NotFoundExc'
+
+
+class APIUrls(object):
+ """
+ Class to manage API documentation URLs.
+ * Indexes all routes documented using apidoc's decorators.
+ * Tracks endpoint/request processing method relationships for use
+ in generating related urls in API documentation
+ Relies on the load_controllers logic in main.py for initialization.
+
+ """
+ apidoc_routes = {}
+ method_endpoints = {}
+
+ @classmethod
+ def get_app_endpoints(cls):
+ return cls.apidoc_routes
+
+ @classmethod
+ def get_method_endpoints(cls, fname):
+ if len(cls.method_endpoints) == 0:
+ cls.method_endpoints = cls.group_routes_by_method()
+ return cls.method_endpoints[fname]
+
+ @classmethod
+ def group_routes_by_method(cls):
+ """
+ Group URL endpoints according to their processing method.
+ Returns:
+ A dict where keys are the processing method names, and values
+ are the routes that are bound to the key method.
+ """
+ endpoints = {}
+ for rule in app.url_map.iter_rules():
+ rule_dict = {'rule': rule.rule,
+ 'methods': rule.methods}
+ if rule.endpoint not in endpoints:
+ endpoints[rule.endpoint] = [rule_dict]
+ else:
+ endpoints[rule.endpoint].append(rule_dict)
+ return endpoints
+
+ @classmethod
+ def index_add_route(cls, route, docstring):
+ """
+ Add a route to the self-documenting API reference
+ """
+ if route not in cls.apidoc_routes:
+ cls.apidoc_routes[route] = docstring
+
+
+class route(object):
+ """
+ Decorate an API method to register it in the API doc route index
+ and create the corresponding Flask route.
+ Caution: decorating a method with this requires to also decorate it
+ __at least__ with @returns, or breaks the decorated endpoint
+ Args:
+ route: the documentation page's route
+ noargs: set to True if the route has no arguments, and its result
+ should be displayed anytime its documentation is requested
+ """
+ def __init__(self, route, noargs=False):
+ self.route = route
+ self.noargs = noargs
+
+ def __call__(self, f):
+ APIUrls.index_add_route(self.route, f.__doc__)
+
+ @wraps(f)
+ def doc_func(*args, **kwargs):
+ return f(call_args=(args, kwargs),
+ doc_route=self.route,
+ noargs=self.noargs)
+
+ if not self.noargs:
+ app.add_url_rule(self.route, f.__name__, doc_func)
+
+ return doc_func
+
+
+class arg(object):
+ """
+ Decorate an API method to display an argument's information on the doc
+ page specified by @route above.
+ Args:
+ name: the argument's name. MUST match the method argument's name to
+ create the example request URL.
+ default: the argument's default value
+ argtype: the argument's type (map, dict, list, tuple...)
+ argdoc: the argument's documentation string
+ """
+ def __init__(self, name, default, argtype, argdoc):
+ self.doc_dict = {
+ 'name': name,
+ 'type': argtype,
+ 'doc': argdoc,
+ 'default': default
+ }
+
+ def __call__(self, f):
+ @wraps(f)
+ def arg_fun(*args, **kwargs):
+ if 'args' in kwargs:
+ kwargs['args'].append(self.doc_dict)
+ else:
+ kwargs['args'] = [self.doc_dict]
+ return f(*args, **kwargs)
+ return arg_fun
+
+
+class raises(object):
+ """
+ Decorate an API method to display information pertaining to an exception
+ that can be raised by this method.
+ Args:
+ exc: the exception name
+ doc: the exception's documentation string
+ """
+ def __init__(self, exc, doc):
+ self.exc_dict = {
+ 'exc': exc,
+ 'doc': doc
+ }
+
+ def __call__(self, f):
+ @wraps(f)
+ def exc_fun(*args, **kwargs):
+ if 'excs' in kwargs:
+ kwargs['excs'].append(self.exc_dict)
+ else:
+ kwargs['excs'] = [self.exc_dict]
+ return f(*args, **kwargs)
+ return exc_fun
+
+
+def make_response_from_mimetype(rv, env):
+
+ def wants_html(best_match):
+ return best_match == 'text/html' and \
+ request.accept_mimetypes[best_match] > \
+ request.accept_mimetypes['application/json']
+
+ def wants_yaml(best_match):
+ return best_match == 'application/yaml' and \
+ request.accept_mimetypes[best_match] > \
+ request.accept_mimetypes['application/json']
+
+ if isinstance(rv, dict) or isinstance(rv, list):
+ acc_mime = ['application/json', 'application/yaml', 'text/html']
+ best_match = request.accept_mimetypes.best_match(acc_mime)
+ # return a template render
+ if wants_html(best_match):
+ data = json.dumps(rv, sort_keys=True,
+ indent=4, separators=(',', ': '))
+ env['response_data'] = data
+ env['request'] = request
+ rv = app.response_class(render_template('apidoc.html', **env),
+ content_type='text/html')
+ # return formatted yaml
+ elif wants_yaml(best_match):
+ rv = app.response_class(
+ yaml.dump(rv),
+ content_type='application/yaml')
+ # return formatted json
else:
- acc.append(rpath+'/')
- yield from split_path(rpath, acc)
-
- url_doc_endpoints = set()
- for rule in rules:
- url_rule = rule['rule']
- url_doc_endpoints.add(url_rule)
- if '<' in url_rule or '>' in url_rule:
- continue
- acc = []
- for rpath in split_path(url_rule, acc):
- if rpath in url_doc_endpoints:
- continue
- yield rpath
- url_doc_endpoints.add(rpath)
-
-
-def install_browsable_api_endpoints():
- """Install browsable endpoints.
-
- """
- url_doc_endpoints = _create_url_doc_endpoints(main.rules())
- for url_doc in url_doc_endpoints:
- endpoint_name = 'doc_api_' + url_doc.strip('/').replace('/', '_')
-
- def view_func(url_doc=url_doc):
- return utils.filter_endpoints(main.rules(),
- url_doc)
- app.add_url_rule(rule=url_doc,
- endpoint=endpoint_name,
- view_func=view_func,
- methods=['GET'])
+ # jsonify is unhappy with lists in Flask 0.10.1, use json.dumps
+ rv = app.response_class(
+ json.dumps(rv),
+ content_type='application/json')
+ return rv
+
+
+class returns(object):
+ """
+ Decorate an API method to display information about its return value.
+ Caution: this MUST be the last decorator in the apidoc decorator stack,
+ or the decorated endpoint breaks
+ Args:
+ rettype: the return value's type (map, dict, list, tuple...)
+ retdoc: the return value's documentation string
+ """
+ def __init__(self, rettype=None, retdoc=None):
+ self.return_dict = {
+ 'type': rettype,
+ 'doc': retdoc
+ }
+
+ def filter_api_url(self, endpoint, route_re, noargs):
+ doc_methods = {'GET', 'HEAD', 'OPTIONS'}
+ if re.match(route_re, endpoint['rule']):
+ if endpoint['methods'] == doc_methods and not noargs:
+ return False
+ return True
+
+ def __call__(self, f):
+ @wraps(f)
+ def ret_fun(*args, **kwargs):
+ # Build documentation
+ env = {
+ 'docstring': f.__doc__,
+ 'route': kwargs['doc_route'],
+ 'return': self.return_dict
+ }
+
+ for arg in ['args', 'excs']:
+ if arg in kwargs:
+ env[arg] = kwargs[arg]
+
+ route_re = re.compile('.*%s$' % kwargs['doc_route'])
+ endpoint_list = APIUrls.get_method_endpoints(f.__name__)
+ other_urls = [url for url in endpoint_list if
+ self.filter_api_url(url, route_re, kwargs['noargs'])]
+ env['urls'] = other_urls
+
+ # Build example endpoint URL
+ if 'args' in env:
+ defaults = {arg['name']: arg['default'] for arg in env['args']}
+ env['example'] = url_for(f.__name__, **defaults)
+
+ # Prepare and send to mimetype selector if it's not a doc request
+ if re.match(route_re, request.url) and not kwargs['noargs']:
+ return app.response_class(
+ render_template('apidoc.html', **env),
+ content_type='text/html')
+
+ cargs, ckwargs = kwargs['call_args']
+ rv = f(*cargs, **ckwargs)
+ return make_response_from_mimetype(rv, env)
+ return ret_fun
diff --git a/swh/web/ui/main.py b/swh/web/ui/main.py
index beb64b066..00c5bac45 100644
--- a/swh/web/ui/main.py
+++ b/swh/web/ui/main.py
@@ -1,147 +1,139 @@
# Copyright (C) 2015 The Software Heritage developers
# See the AUTHORS file at the top-level directory of this distribution
# License: GNU Affero General Public License version 3, or any later version
# See top-level LICENSE file for more information
import logging
import os
+import json
-from flask.ext.api import FlaskAPI
+from flask import Flask
from swh.core import config
from swh.web.ui.renderers import RENDERERS, urlize_api_links
from swh.web.ui.renderers import safe_docstring_display
from swh.web.ui.renderers import revision_id_from_url
from swh.storage import get_storage
DEFAULT_CONFIG = {
'storage_args': ('list[str]', ['http://localhost:5000/']),
'storage_class': ('str', 'remote_storage'),
'log_dir': ('string', '/tmp/swh/log'),
'debug': ('bool', None),
'host': ('string', '127.0.0.1'),
'port': ('int', 6543),
'secret_key': ('string', 'development key'),
'max_log_revs': ('int', 25),
}
-
# api's definition
-app = FlaskAPI(__name__)
+app = Flask(__name__)
app.jinja_env.filters['urlize_api_links'] = urlize_api_links
app.jinja_env.filters['safe_docstring_display'] = safe_docstring_display
app.jinja_env.filters['revision_id_from_url'] = revision_id_from_url
-AUTODOC_ENDPOINT_INSTALLED = False
-
def read_config(config_file):
"""Read the configuration file `config_file`, update the app with
parameters (secret_key, conf) and return the parsed configuration as a
dict"""
conf = config.read(config_file, DEFAULT_CONFIG)
config.prepare_folders(conf, 'log_dir')
conf['storage'] = get_storage(conf['storage_class'], conf['storage_args'])
return conf
def load_controllers():
"""Load the controllers for the application.
"""
from swh.web.ui import views, apidoc # flake8: noqa
- # side-effects here (install autodoc endpoints so do it only once!)
- global AUTODOC_ENDPOINT_INSTALLED
- if not AUTODOC_ENDPOINT_INSTALLED:
- apidoc.install_browsable_api_endpoints()
- AUTODOC_ENDPOINT_INSTALLED = True
-
def rules():
"""Returns rules from the application in dictionary form.
Beware, must be called after swh.web.ui.main.load_controllers funcall.
Returns:
Generator of application's rules.
"""
for rule in app.url_map._rules:
yield {'rule': rule.rule,
'methods': rule.methods,
'endpoint': rule.endpoint}
def storage():
"""Return the current application's storage.
"""
return app.config['conf']['storage']
def run_from_webserver(environ, start_response):
"""Run the WSGI app from the webserver, loading the configuration.
Note: This function is called on a per-request basis so beware the side
effects here!
"""
load_controllers()
config_path = '/etc/softwareheritage/webapp/webapp.ini'
conf = read_config(config_path)
app.secret_key = conf['secret_key']
app.config['conf'] = conf
app.config['DEFAULT_RENDERERS'] = RENDERERS
logging.basicConfig(filename=os.path.join(conf['log_dir'], 'web-ui.log'),
level=logging.INFO)
return app(environ, start_response)
def run_debug_from(config_path, verbose=False):
"""Run the api's server in dev mode.
Note: This is called only once (contrast with the production mode
in run_from_webserver function)
Args:
conf is a dictionary of keywords:
- 'db_url' the db url's access (through psycopg2 format)
- 'content_storage_dir' revisions/directories/contents storage on disk
- 'host' to override the default 127.0.0.1 to open or not the server
to the world
- 'port' to override the default of 5000 (from the underlying layer:
flask)
- 'debug' activate the verbose logs
- 'secret_key' the flask secret key
Returns:
Never
"""
load_controllers()
conf = read_config(config_path)
app.secret_key = conf['secret_key']
app.config['conf'] = conf
app.config['DEFAULT_RENDERERS'] = RENDERERS
host = conf.get('host', '127.0.0.1')
port = conf.get('port')
debug = conf.get('debug')
log_file = os.path.join(conf['log_dir'], 'web-ui.log')
logging.basicConfig(level=logging.DEBUG if verbose else logging.INFO,
handlers=[logging.FileHandler(log_file),
logging.StreamHandler()])
app.run(host=host, port=port, debug=debug)
diff --git a/swh/web/ui/templates/api.html b/swh/web/ui/templates/api.html
index 629e6a749..fff40c41b 100644
--- a/swh/web/ui/templates/api.html
+++ b/swh/web/ui/templates/api.html
@@ -1,194 +1,13 @@
-<!DOCTYPE html>
-<html>
- <head>
- {% block head %}
-
- {% block meta %}
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
- <meta name="robots" content="NONE,NOARCHIVE" />
- {% endblock %}
-
- <title>{% block title %}Software Heritage API{% endblock %}</title>
-
- {% block style %}
- {% block bootstrap_theme %}
- <link rel="stylesheet" type="text/css" href="{{url_for('flask-api.static', filename='css/bootstrap.min.css')}}"/>
- <link rel="stylesheet" type="text/css" href="{{url_for('flask-api.static', filename='css/bootstrap-tweaks.css')}}"/>
- {% endblock %}
- <link rel="stylesheet" type="text/css" href="{{url_for('flask-api.static', filename='css/prettify.css')}}"/>
- <link rel="stylesheet" type="text/css" href="{{url_for('flask-api.static', filename='css/default.css')}}"/>
- {% endblock %}
-
- {% endblock %}
- </head>
-
- <body class="{% block bodyclass %}{% endblock %} container">
-
- <div class="wrapper">
-
- {% block navbar %}
- <div class="navbar {% block bootstrap_navbar_variant %}navbar-inverse{% endblock %}">
- <div class="navbar-inner">
- <div class="container-fluid">
- <span href="/">
- {% block branding %}<a class="navbar-brand" rel="nofollow" href='{{url_for('homepage')}}'>Software Heritage API v1</span></a>{% endblock %}
- </span>
- <ul class="nav pull-right">
- {% block userlinks %}
- <!--{ if user.is_authenticated }
- <li class="dropdown">
- <a href="#" class="dropdown-toggle" data-toggle="dropdown">
- {{ user }}
- <b class="caret"></b>
- </a>
- <ul class="dropdown-menu">
- <li>optional_logout request</li>
- </ul>
- </li>
- { else }-->
- <li><!-- optional_login request --></li>
- <!--{ endif }-->
- {% endblock %}
- </ul>
- </div>
- </div>
- </div>
- {% endblock %}
-
- <!--
- {% block breadcrumbs %}
- <ul class="breadcrumb">
- {% for breadcrumb_name, breadcrumb_url in breadcrumblist %}
- <li>
- <a href="{{ breadcrumb_url }}" {% if forloop.last %}class="active"{% endif %}>{{ breadcrumb_name }}</a> {% if not forloop.last %}<span class="divider">›</span>{% endif %}
- </li>
- {% endfor %}
- </ul>
- {% endblock %}
- -->
- <div style="height: 50px"></div>
-
- <!-- Content -->
- <div id="content">
-
- {% if 'GET' in allowed_methods %}
- <form id="get-form" class="pull-right">
- <fieldset>
- <div class="btn-group format-selection">
- <a class="btn btn-primary js-tooltip" href='{{ request.get_full_path }}' rel="nofollow" title="Make a GET request on the {{ name }} resource">GET</a>
-
- <button class="btn btn-primary dropdown-toggle js-tooltip" data-toggle="dropdown" title="Specify a format for the GET request">
- <span class="caret"></span>
- </button>
- <ul class="dropdown-menu">
- {% for format in available_formats %}
- <li>
- <a class="js-tooltip format-option" href='<!-- add_query_param request api_settings.URL_FORMAT_OVERRIDE format -->' rel="nofollow" title="Make a GET request on the {{ name }} resource with the format set to `{{ format }}`">{{ format }}</a>
- </li>
- {% endfor %}
- </ul>
- </div>
-
- </fieldset>
- </form>
- {% endif %}
-
- <!--{% if 'OPTIONS' in allowed_methods %}
- <form class="button-form" action="{{ request.full_path }}" method="POST" class="pull-right">
- <- csrf_token ->
- <input type="hidden" name="_method" value="OPTIONS" />
- <button class="btn btn-primary js-tooltip" title="Make an OPTIONS request on the resource">OPTIONS</button>
- </form>
- {% endif %}-->
-
- {% if 'DELETE' in allowed_methods %}
- <form class="button-form" action="{{ request.full_path }}" method="POST" class="pull-right">
- <!-- csrf_token -->
- <input type="hidden" name="_method" value="DELETE" />
- <button class="btn btn-danger js-tooltip" title="Make a DELETE request on the resource">DELETE</button>
- </form>
- {% endif %}
-
- <div class="content-main">
- <div class="page-header"><h1>{{ view_name }}</h1></div>
- {% if view_description %}
- <div style="margin-top: -10px; margin-bottom: 10px">
- {{ view_description | safe_docstring_display | safe}}
- </div>
- {% endif %}
- <div class="request-info" style="clear: both" >
- <pre><b>{{ request.method }}</b> {{ request.full_path }}</pre>
- </div>
- <div class="response-info">
- <pre><div class="meta nocode"><b>HTTP {{ status }}</b>{% autoescape off %}
-{% for key, val in headers.items() %}<b>{{ key }}:</b> <span class="lit">{{ val|e }}<!--{ val|break_long_headers|urlize_quoted_links }--></span>
-{% endfor %}
-</div>{% if content %}{{ content|urlize_api_links }}{% endif %}<!-- |urlize_quoted_links --></pre>{% endautoescape %}
- </div>
- </div>
-
-
- {% if 'POST' in allowed_methods or 'PUT' in allowed_methods or 'PATCH' in allowed_methods %}
- <div>
- <div class="well">
- <div id="generic-content-form">
- <form action="{{ request.full_path }}" method="POST" class="form-horizontal">
- <fieldset>
-<div class="control-group">
- <label for="id__content_type" class="control-label">Media type:</label>
- <div class="controls">
- <select id="id__content_type" name="_content_type">
-<option value="application/json" selected="selected">application/json</option>
-<option value="application/x-www-form-urlencoded">application/x-www-form-urlencoded</option>
-<option value="multipart/form-data">multipart/form-data</option>
-</select>
- <span class="help-block"></span>
- </div>
- </div>
- <div class="control-group">
- <label for="id__content" class="control-label">Content:</label>
- <div class="controls">
- <textarea name="_content" cols="40" rows="10"></textarea>
- </div>
- </div>
- <div class="form-actions">
- {% if 'POST' in allowed_methods %}
- <button class="btn btn-primary" title="Make a POST request on the resource">POST</button>
- {% endif %}
- {% if 'PUT' in allowed_methods %}
- <button class="btn btn-primary js-tooltip" name="_method" value="PUT" title="Make a PUT request on the resource">PUT</button>
- {% endif %}
- {% if 'PATCH' in allowed_methods %}
- <button class="btn btn-primary js-tooltip" name="_method" value="PATCH" title="Make a PATCH request on the resource">PATCH</button>
- {% endif %}
- </div>
- </fieldset>
- </form>
- </div>
- </div>
- </div>
- {% endif %}
-
- </div>
- <!-- END content-main -->
-
- </div>
- <!-- END Content -->
-
- <div id="push"></div>
-
- </div>
-
- </div><!-- ./wrapper -->
-
- {% block footer %}
- {% endblock %}
-
- {% block script %}
- <script src="{{url_for('flask-api.static', filename='js/jquery.min.js')}}"></script>
- <script src="{{url_for('flask-api.static', filename='js/bootstrap.min.js')}}"></script>
- <script src="{{url_for('flask-api.static', filename='js/prettify-min.js')}}"></script>
- <script src="{{url_for('flask-api.static', filename='js/default.js')}}"></script>
- {% endblock %}
- </body>
-</html>
+{% extends "layout.html" %}
+{% block title %}Software Heritage API Overview{% endblock %}
+{% block content %}
+<div class="api-doc">
+ {% for route, doc in doc_routes %}
+ <div class="api-doc-route">
+ <h2> <a href="{{ route }}">{{ route }}</a> </h2>
+ {{ doc }}
+ </div>
+ </br>
+ {% endfor %}
+</div>
+{% endblock %}
diff --git a/swh/web/ui/templates/apidoc.html b/swh/web/ui/templates/apidoc.html
new file mode 100644
index 000000000..2c8c5cca0
--- /dev/null
+++ b/swh/web/ui/templates/apidoc.html
@@ -0,0 +1,84 @@
+{% extends "layout.html" %}
+{% block title %}Software Heritage API{% endblock %}
+{% block content %}
+
+{% if docstring %}
+<div class="docstring">
+ <h2> Overview </h2>
+ {{ docstring | safe }}
+</div>
+{% endif %}
+{% if response_data and response_data is not none %}
+<div class="response-data">
+ <h2> Request </h2>
+ <pre><strong>{{ request.method }}</strong> {{ request.url }}</pre>
+ <h2> Result </h2>
+ <pre> {% autoescape off %} {{ response_data | urlize_api_links }} {% endautoescape %} </pre>
+</div>
+{% endif %}
+<hr/>
+<div class="doc-urls">
+ <table class="m-x-auto table">
+ <thead>
+ <tr>
+ <th>URL</th>
+ <th>Allowed Methods</th>
+ </tr>
+ </thead>
+ <tbody>
+ {% for url in urls %}
+ <tr>
+ <td>
+ {{ url['rule'] }}
+ </td>
+ <td>
+ {{ url['methods'] | sort | join(', ') }}
+ </td>
+ </tr>
+ {% endfor %}
+ </tbody>
+ </table>
+</div>
+<hr/>
+{% if args and args|length > 0 %}
+<div class="doc-args">
+ <h2> Args </h2>
+ <dl class="doc-argslist dl-horizontal">
+ {% for arg in args %}
+ <dt> {{ arg['name'] }}: {{ arg['type'] }} </dt>
+ <dd> {{ arg['doc'] }} </dd>
+ {% endfor %}
+ </dl>
+</div>
+{% endif %}
+{% if excs and excs|length > 0 %}
+<div class="doc-excs">
+ <h2> Raises </h2>
+ <dl class="doc-excslist dl-horizontal">
+ {% for exc in excs %}
+ <dt> {{ exc['exc'] }} </dt>
+ <dd> {{ exc['doc'] }} </dd>
+ {% endfor %}
+ </dl>
+</div>
+{% endif %}
+{% if return %}
+<div class="doc-return">
+ <h2> Returns </h2>
+ <dl class="doc-return dl-horizontal">
+ <dt>{{ return['type'] }}</dt>
+ <dd>{{ return['doc'] }}</dd>
+ </dl>
+</div>
+{% endif %}
+{% if example %}
+<div class="doc-example">
+ <h2> Example </h2>
+ <dl class="doc-example dl-horizontal">
+ <dd>
+ <a href="{{ example }}">{{ example }}</a>
+ </dd>
+ </dl>
+</div>
+{% endif %}
+{% endblock %}
diff --git a/swh/web/ui/tests/test_apidoc.py b/swh/web/ui/tests/test_apidoc.py
new file mode 100644
index 000000000..d7268003e
--- /dev/null
+++ b/swh/web/ui/tests/test_apidoc.py
@@ -0,0 +1,430 @@
+# Copyright (C) 2015 The Software Heritage developers
+# See the AUTHORS file at the top-level directory of this distribution
+# License: GNU Affero General Public License version 3, or any later version
+# See top-level LICENSE file for more information
+
+
+import json
+import yaml
+
+from unittest.mock import MagicMock, patch
+from nose.tools import istest
+
+from flask import Response
+
+from swh.web.ui import apidoc
+from swh.web.ui.tests import test_app
+
+
+class APIDocTestCase(test_app.SWHApidocTestCase):
+
+ def setUp(self):
+ self.arg_dict = {
+ 'name': 'my_pretty_arg',
+ 'default': 'some default value',
+ 'type': 'str',
+ 'doc': 'this arg does things'
+ }
+ self.stub_excs = [{'exc': 'catastrophic_exception',
+ 'doc': 'My exception documentation'}]
+ self.stub_args = [{'name': 'stub_arg',
+ 'default': 'some_default'}]
+ self.stub_rule_list = [
+ {'rule': 'some/route/with/args/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}},
+ {'rule': 'some/doc/route/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}},
+ {'rule': 'some/other/route/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}}
+ ]
+ self.stub_return = {
+ 'type': 'some_return_type',
+ 'doc': 'a dict with amazing properties'
+ }
+
+ @patch('swh.web.ui.apidoc.APIUrls')
+ @patch('swh.web.ui.apidoc.app')
+ @istest
+ def apidoc_route(self, mock_app, mock_api_urls):
+ # given
+ decorator = apidoc.route('/some/url/for/doc/')
+ mock_fun = MagicMock(return_value=123)
+ mock_fun.__doc__ = 'Some documentation'
+ mock_fun.__name__ = 'some_fname'
+ decorated = decorator.__call__(mock_fun)
+
+ # when
+ decorated('some', 'value', kws='and a kw')
+
+ # then
+ mock_fun.assert_called_once_with(
+ call_args=(('some', 'value'), {'kws': 'and a kw'}),
+ doc_route='/some/url/for/doc/',
+ noargs=False
+ )
+ mock_api_urls.index_add_route.assert_called_once_with(
+ '/some/url/for/doc/',
+ 'Some documentation')
+ mock_app.add_url_rule.assert_called_once_with(
+ '/some/url/for/doc/', 'some_fname', decorated)
+
+ @istest
+ def apidoc_arg_noprevious(self):
+ # given
+ decorator = apidoc.arg('my_pretty_arg',
+ default='some default value',
+ argtype='str',
+ argdoc='this arg does things')
+ mock_fun = MagicMock(return_value=123)
+ decorated = decorator.__call__(mock_fun)
+
+ # when
+ decorated(call_args=((), {}), doc_route='some/route/')
+
+ # then
+ mock_fun.assert_called_once_with(
+ call_args=((), {}),
+ doc_route='some/route/',
+ args=[self.arg_dict]
+ )
+
+ @istest
+ def apidoc_arg_previous(self):
+ # given
+ decorator = apidoc.arg('my_other_arg',
+ default='some other value',
+ argtype='str',
+ argdoc='this arg is optional')
+ mock_fun = MagicMock(return_value=123)
+ decorated = decorator.__call__(mock_fun)
+
+ # when
+ decorated(call_args=((), {}),
+ doc_route='some/route/',
+ args=[self.arg_dict])
+
+ # then
+ mock_fun.assert_called_once_with(
+ call_args=((), {}),
+ doc_route='some/route/',
+ args=[self.arg_dict,
+ {'name': 'my_other_arg',
+ 'default': 'some other value',
+ 'type': 'str',
+ 'doc': 'this arg is optional'}])
+
+ @istest
+ def apidoc_raises_noprevious(self):
+ # given
+ decorator = apidoc.raises(exc='catastrophic_exception',
+ doc='My exception documentation')
+ mock_fun = MagicMock(return_value=123)
+ decorated = decorator.__call__(mock_fun)
+
+ # when
+ decorated(call_args=((), {}), doc_route='some/route/')
+
+ # then
+ mock_fun.assert_called_once_with(
+ call_args=((), {}),
+ doc_route='some/route/',
+ excs=self.stub_excs
+ )
+
+ @istest
+ def apidoc_raises_previous(self):
+ # given
+ decorator = apidoc.raises(exc='cataclysmic_exception',
+ doc='Another documentation')
+ mock_fun = MagicMock(return_value=123)
+ decorated = decorator.__call__(mock_fun)
+ expected_excs = self.stub_excs + [{
+ 'exc': 'cataclysmic_exception',
+ 'doc': 'Another documentation'}]
+
+ # when
+ decorated(call_args=((), {}),
+ doc_route='some/route/',
+ excs=self.stub_excs)
+
+ # then
+ mock_fun.assert_called_once_with(
+ call_args=((), {}),
+ doc_route='some/route/',
+ excs=expected_excs)
+
+ @patch('swh.web.ui.apidoc.render_template')
+ @patch('swh.web.ui.apidoc.url_for')
+ @patch('swh.web.ui.apidoc.APIUrls')
+ @patch('swh.web.ui.apidoc.request')
+ @istest
+ def apidoc_returns_doc_call(self,
+ mock_request,
+ mock_api_urls,
+ mock_url_for,
+ mock_render):
+ # given
+ decorator = apidoc.returns(rettype='some_return_type',
+ retdoc='a dict with amazing properties')
+ mock_fun = MagicMock(return_value=123)
+ mock_fun.__name__ = 'some_fname'
+ mock_fun.__doc__ = 'Some documentation'
+ decorated = decorator.__call__(mock_fun)
+
+ mock_api_urls.get_method_endpoints.return_value = self.stub_rule_list
+
+ mock_request.url = 'http://my-domain.tld/some/doc/route/'
+ mock_url_for.return_value = 'http://my-domain.tld/meaningful_route/'
+
+ expected_env = {
+ 'urls': [{'rule': 'some/route/with/args/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}},
+ {'rule': 'some/other/route/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}}],
+ 'docstring': 'Some documentation',
+ 'args': self.stub_args,
+ 'excs': self.stub_excs,
+ 'route': 'some/doc/route/',
+ 'example': 'http://my-domain.tld/meaningful_route/',
+ 'return': self.stub_return
+ }
+
+ # when
+ decorated(
+ docstring='Some documentation',
+ call_args=(('some', 'args'), {'kw': 'kwargs'}),
+ args=self.stub_args,
+ excs=self.stub_excs,
+ doc_route='some/doc/route/',
+ noargs=False
+ )
+
+ # then
+ self.assertEqual(mock_fun.call_args_list, []) # function not called
+ mock_render.assert_called_once_with(
+ 'apidoc.html',
+ **expected_env
+ )
+
+ @patch('swh.web.ui.apidoc.make_response_from_mimetype')
+ @patch('swh.web.ui.apidoc.url_for')
+ @patch('swh.web.ui.apidoc.APIUrls')
+ @patch('swh.web.ui.apidoc.request')
+ @istest
+ def apidoc_returns_noargs(self,
+ mock_request,
+ mock_api_urls,
+ mock_url_for,
+ mock_make_resp):
+
+ # given
+ decorator = apidoc.returns(rettype='some_return_type',
+ retdoc='a dict with amazing properties')
+ mock_fun = MagicMock(return_value=123)
+ mock_fun.__name__ = 'some_fname'
+ mock_fun.__doc__ = 'Some documentation'
+ decorated = decorator.__call__(mock_fun)
+
+ mock_api_urls.get_method_endpoints.return_value = [
+ {'rule': 'some/doc/route/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}}]
+
+ mock_request.url = 'http://my-domain.tld/some/doc/route/'
+
+ # when
+ decorated(
+ call_args=((), {}),
+ doc_route='some/doc/route/',
+ noargs=True
+ )
+
+ # then
+ mock_fun.assert_called_once_with()
+ mock_make_resp.assert_called_once_with(
+ 123,
+ {
+ 'urls': [
+ {'rule': 'some/doc/route/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}}],
+ 'docstring': 'Some documentation',
+ 'route': 'some/doc/route/',
+ 'return': {'type': 'some_return_type',
+ 'doc': 'a dict with amazing properties'}
+ }
+ )
+
+ @patch('swh.web.ui.apidoc.make_response_from_mimetype')
+ @patch('swh.web.ui.apidoc.url_for')
+ @patch('swh.web.ui.apidoc.APIUrls')
+ @patch('swh.web.ui.apidoc.request')
+ @istest
+ def apidoc_return_endpoint_call(self,
+ mock_request,
+ mock_api_urls,
+ mock_url_for,
+ mock_resp):
+ # given
+ decorator = apidoc.returns(rettype='some_return_type',
+ retdoc='a dict with amazing properties')
+ mock_fun = MagicMock(return_value=123)
+ mock_fun.__name__ = 'some_fname'
+ mock_fun.__doc__ = 'Some documentation'
+ decorated = decorator.__call__(mock_fun)
+
+ mock_api_urls.get_method_endpoints.return_value = self.stub_rule_list
+
+ mock_request.url = 'http://my-domain.tld/some/arg/route/'
+ mock_url_for.return_value = 'http://my-domain.tld/some/arg/route'
+
+ # when
+ decorated(
+ docstring='Some documentation',
+ call_args=(('some', 'args'), {'kw': 'kwargs'}),
+ args=self.stub_args,
+ excs=self.stub_excs,
+ noargs=False,
+ doc_route='some/doc/route/',
+ )
+
+ # then
+ mock_fun.assert_called_once_with('some', 'args', kw='kwargs')
+ mock_resp.assert_called_with(
+ 123,
+ {
+ 'urls': [{'rule': 'some/route/with/args/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}},
+ {'rule': 'some/other/route/',
+ 'methods': {'GET', 'HEAD', 'OPTIONS'}}],
+ 'docstring': 'Some documentation',
+ 'args': self.stub_args,
+ 'excs': self.stub_excs,
+ 'route': 'some/doc/route/',
+ 'example': 'http://my-domain.tld/some/arg/route',
+ 'return': self.stub_return
+ }
+ )
+
+ @patch('swh.web.ui.apidoc.json')
+ @patch('swh.web.ui.apidoc.request')
+ @patch('swh.web.ui.apidoc.render_template')
+ @istest
+ def apidoc_make_response_html(self,
+ mock_render,
+ mock_request,
+ mock_json):
+ # given
+ data = {'data': [12, 34],
+ 'id': 'adc83b19e793491b1c6ea0fd8b46cd9f32e592fc'}
+ env = {'my_key': 'my_display_value'}
+
+ def mock_mimetypes(key):
+ mimetypes = {
+ 'text/html': 10,
+ 'application/json': 0.1,
+ 'application/yaml': 0.1
+ }
+ return mimetypes[key]
+ accept_mimetypes = MagicMock()
+ accept_mimetypes.__getitem__.side_effect = mock_mimetypes
+ accept_mimetypes.best_match = MagicMock(
+ return_value='text/html')
+ mock_request.accept_mimetypes = accept_mimetypes
+
+ mock_json.dumps.return_value = json.dumps(data)
+
+ expected_env = {
+ 'my_key': 'my_display_value',
+ 'response_data': json.dumps(data),
+ 'request': mock_request
+ }
+
+ # when
+ rv = apidoc.make_response_from_mimetype(data, env)
+
+ # then
+ self.assertEqual(mock_request.accept_mimetypes['text/html'], 10)
+ mock_render.assert_called_with(
+ 'apidoc.html',
+ **expected_env
+ )
+ self.assertEqual(rv.mimetype, 'text/html')
+
+ @patch('swh.web.ui.apidoc.json')
+ @patch('swh.web.ui.apidoc.request')
+ @istest
+ def apidoc_make_response_json(self,
+ mock_request,
+ mock_json):
+ # given
+ data = {'data': [12, 34],
+ 'id': 'adc83b19e793491b1c6ea0fd8b46cd9f32e592fc'}
+ env = {'my_key': 'my_display_value'}
+
+ def mock_mimetypes(key):
+ mimetypes = {
+ 'application/json': 10,
+ 'text/html': 0.1,
+ 'application/yaml': 0.1
+ }
+ return mimetypes[key]
+ accept_mimetypes = MagicMock()
+ accept_mimetypes.__getitem__.side_effect = mock_mimetypes
+ accept_mimetypes.best_match = MagicMock(
+ return_value='application/json')
+ mock_request.accept_mimetypes = accept_mimetypes
+ mock_json.dumps.return_value = json.dumps(data)
+
+ # when
+ rv = apidoc.make_response_from_mimetype(data, env)
+
+ # then
+ mock_json.dumps.assert_called_once_with(data)
+
+ self.assertEqual(rv.status_code, 200)
+ self.assertEqual(rv.mimetype, 'application/json')
+ self.assertEqual(data, json.loads(rv.data.decode('utf-8')))
+
+ @patch('swh.web.ui.apidoc.yaml')
+ @patch('swh.web.ui.apidoc.request')
+ @istest
+ def apidoc_make_response_yaml(self,
+ mock_request,
+ mock_yaml):
+ # given
+ data = ['adc83b19e793491b1c6ea0fd8b46cd9f32e592fc']
+ env = {'my_key': 'my_display_value'}
+
+ def mock_mimetypes(key):
+ mimetypes = {
+ 'application/yaml': 10,
+ 'application/json': 0.1,
+ 'text/html': 0.1
+ }
+ return mimetypes[key]
+ accept_mimetypes = MagicMock()
+ accept_mimetypes.__getitem__.side_effect = mock_mimetypes
+ accept_mimetypes.best_match = MagicMock(
+ return_value='application/yaml')
+ mock_request.accept_mimetypes = accept_mimetypes
+ mock_yaml.dump.return_value = yaml.dump(data)
+
+ # when
+ rv = apidoc.make_response_from_mimetype(data, env)
+
+ # then
+ mock_yaml.dump.assert_called_once_with(data)
+
+ self.assertEqual(rv.status_code, 200)
+ self.assertEqual(rv.mimetype, 'application/yaml')
+ self.assertEqual(data, yaml.load(rv.data.decode('utf-8')))
+
+ @istest
+ def apidoc_make_response_not_list_dict(self):
+ # given
+ incoming = Response()
+
+ # when
+ rv = apidoc.make_response_from_mimetype(incoming, {})
+
+ # then
+ self.assertEqual(rv, incoming)
diff --git a/swh/web/ui/tests/test_app.py b/swh/web/ui/tests/test_app.py
index 140f357d6..2c96e82c7 100644
--- a/swh/web/ui/tests/test_app.py
+++ b/swh/web/ui/tests/test_app.py
@@ -1,86 +1,96 @@
# Copyright (C) 2015 The Software Heritage developers
# See the AUTHORS file at the top-level directory of this distribution
# License: GNU Affero General Public License version 3, or any later version
# See top-level LICENSE file for more information
# Functions defined here are NOT DESIGNED FOR PRODUCTION
import unittest
from swh.storage.api.client import RemoteStorage as Storage
from swh.web.ui import renderers, main
from flask.ext.testing import TestCase
# Because the Storage's __init__ function does side effect at startup...
class RemoteStorageAdapter(Storage):
def __init__(self, base_url):
self.base_url = base_url
def _init_mock_storage(base_url='https://somewhere.org:4321'):
"""Instanciate a remote storage whose goal is to be mocked in a test
context.
NOT FOR PRODUCTION
Returns:
An instance of swh.storage.api.client.RemoteStorage destined to be
mocked (it does not do any rest call)
"""
return RemoteStorageAdapter(base_url) # destined to be used as mock
def create_app(base_url='https://somewhere.org:4321'):
"""Function to initiate a flask app with storage designed to be mocked.
Returns:
Tuple:
- app test client (for testing api, client decorator from flask)
- application's full configuration
- the storage instance to stub and mock
- the main app without any decoration
NOT FOR PRODUCTION
"""
storage = _init_mock_storage(base_url)
# inject the mock data
conf = {'storage': storage,
'max_log_revs': 25}
main.app.config.update({'conf': conf})
main.app.config['DEFAULT_RENDERERS'] = renderers.RENDERERS
if not main.app.config['TESTING']: # HACK: install controllers only once!
main.app.config['TESTING'] = True
main.load_controllers()
return main.app.test_client(), main.app.config, storage, main.app
+class SWHApidocTestCase(unittest.TestCase):
+ """Testing APIDoc class.
+
+ """
+ @classmethod
+ def setUpClass(cls):
+ cls.app, cls.app_config, cls.storage, _ = create_app()
+ cls.maxDiff = None
+
+
class SWHApiTestCase(unittest.TestCase):
"""Testing API class.
"""
@classmethod
def setUpClass(cls):
cls.app, cls.app_config, cls.storage, _ = create_app()
cls.maxDiff = None
class SWHViewTestCase(TestCase):
"""Testing view class.
cf. http://pythonhosted.org/Flask-Testing/
"""
# This inhibits template rendering
# render_templates = False
def create_app(self):
"""Initialize a Flask-Testing application instance to test view
without template rendering
"""
_, _, _, appToDecorate = create_app()
return appToDecorate